# kind: Scope

Конфигурация предназначена для реализации ограничивающих правил валидации. В случае несовпадения хоть с одной политикой безопасности действия пользователя будут неприменимы в рамках кластера.

Пример реализации «kind: Scope»:

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
  namespace: $NAMESPACE
spec:
  type: validation
  items:
    - name: kubelatte-validation-rule-simples
      match:
        kinds:
          - apiGroups:
              - ''
            kinds:
              - Pod
        operations:
          - CREATE
      rule:
        simples:
          - name: KB-OSE-3
            path: spec.volumes[?configMap == null && emptyDir == null && projected == null && downwardAPI == null]
            value: .*
            action: deny
            message: 'Обнаружены элементы, использующие Persistent Volumes (PV)'
```


| Поле            | Назначение                                                                                                                                                                                                                                                                                     |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type            | Тип режима работы, для которого описаны ограничения <br><br> Возможные зачения mutation, validation (соответсвенно для использования ограничений для мутации или валидации). По умолчанию режим мутации. Для режима мутации - разрешающие правила ; для режима валидации - запрещающие правила |
| [match](#match) | Правила, ограничивающие создание ресурса.                                                                                                                                                                                                                                                      |
| [rule](#rule)   | Поле, в котором описаны инсрукции валидации правил                                                                                                                                                                                                                                             |


## match

Правила выбора запросов для проведения валидации. Если указанные в этой секции условия выполнены – валидация будет производится

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        kinds: # список ресурсов, которые валидируются
          - kinds:
              - Deployment
              - StatefulSet
            apiGroups:
              - '*'
        userInfo:
          username: .*some-username.* # review.userInfo.username
        name: object-namw # проверка по имени ресурса request.object.metadata.name при operation CREATE/UPDATE и request.oldObject.metadata.name при DELETE
        scope: (* | Cluster | Namespaced) # идентификатор ресурса: cluster / namespace local
        namespaceSelector:
          matchExpressions:
            - key: key
              operator: In
              values:
                - value
        excludedNamespaces: namespace-*,namespace2-popo  # cписок исключенных namespace (поддерживает регулярные выражения)      
        namespaces: # cписок наблюдаемых namespace (поддерживает регулярные выражения)
          - namesapce-1
          - namespace-2 
        operations: # операции (Create - object, UPDATE - object/oldObject), DELETE - oldObject)
          - CREATE
        labelSelector:
          matchExpressions:
            - key: key
              operator: In
              values:
                - value        
 
      rule:
        simples:
          - name: name-rule
            path: spec.group
            value: *\.istio\.io            
            action: allow/deny
            message: Нельзя создавать такое безобразие
```

| Поле                                      | Назначение                                                                                                                      |
|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [kinds](#kinds)                           | Перечень типов ресурсов, которые разрешены к валидации                                                                          |
| [userInfo](#userInfo)                     | Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект (type: validation)                             |
| [name](#name)                             | Наименование объекта, по которому будет происходить валидация. Если нет этого поля, то проверка по имени обекта не производится |
| scope                                     | Идентификатор принадлежности ресурса к scope <br> Возможные значения: '*', Namespaced, Cluster                                  |
| [namespaceSelector](#namespaceSelector)   | Метка (label) на namespace, в рамках которых будет происходить валидация                                                        |
| excludedNamespaces                        | Список исключенных namespace, по которым не будет происходить валидация                                                         |
| namespaces                                | Список namespace, по которым будет происходить валидация                                                                        |
| [operations](#operations)                 | Операции над объектом, по которым будет происходить валидация (CREATE/UPDATE/DELETE)                                            |
| [labelSelector]()                         | Метка (label) на объекте, по которому будет происходить валидация                                                               |
| [annotationSelector](#annotationSelector) | Аннотация на объекте, по которому будет происходить валидация                                                                   |
| [matchConditions](#matchConditions)       | Условия на принятие решения состояния (старого/нового)  конфигурации (валидации/мутации конфигурации)                           |

## kinds
Является обязательным полем, в котором указывается список типов ресурсов, которые разрешены к валидации.

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        kinds:                                          
          - kinds:
              - '*'         # разрешаем все типы ресурсов
            apiGroups:
              - '*'         # разрешаем все apiVersion ресурсов
        ...
```

| Поле      | Назначение                                            |
|-----------|-------------------------------------------------------|
| kinds     | Cписок типов ресурсов, которые разрешены к валидации  |
| apiGroups | Cписок версий ресурсов, которые разрешены к валидации |


## userInfo

Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект (type: validation)

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        userInfo:
          usernameRegex: .* # разрешение для любого username ресурса

          или

          username: name_user # разрешение для ресурса с "username: name_user"
        ...
```

| Поле          | Назначение                                                                                   |
|---------------|----------------------------------------------------------------------------------------------|
| username      | Наименование ServiceAccount/User. Конкретизация пользователя, кто создает объект             |
| usernameRegex | Регулярное выражение для ServiceAccount/User. Конкретизация пользователя, кто создает объект |


## name

Наименование объекта, по которому будет происходить валидация

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        name:
          value: testing-matc

          или

          regex: '.*istio\..*io'
        ...
```

| Поле               | Назначение                                            |
|--------------------|-------------------------------------------------------|
| value              | Наименование валидируемого ресурса                    |
| regex              | Регулярное выражение для имени валидируемого ресурса  |



## namespaceSelector

Если в рамках AdmissionReview отсутствует request.object.metadata.namespace, то проверка считается успешной, проверяются следующие условия в секции match. Если поле отсутствует, то проверка namespace не происходит и проверяются следующие условия в секции match.

Метка (label) на namespace, в рамках которых будет происходить валидация

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        namespaceSelector:
          matchExpressions:
            - key: label-for-validation
              operator: In
              values:
                - value-1
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |

## operations

- CREATE соответствует операции создания объекта. При создании в поле matchConditions передается информация о валидации только нового объекта (object), поле oldObject пустое

- UPDATE соответствует операции обновления объекта. При обновлении в поле matchConditions передается информация о валидации текущего объекта (oldObject) и нового объекта (object)

- DELETE соответствует операции удаления объекта. При удалении в поле matchConditions передается информация о валидации только текущего объекта (oldObject), поле object пустое



## labelSelector

Метка (label) на объекте, по которому будет происходить валидация. Если поле отсутствует, то проверка label не происходит и проверяются следующие условия в секции match.

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        labelSelector:
          matchExpressions:
            - key: label-for-validation
              operator: NotIn
              values:
                - 'false'
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |



## annotationSelector

Аннотация на объекте, по которому будет происходить валидация. Если поле отсутствует, то проверка label не происходит и проверяются следующие условия в секции match.

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        annotationSelector:
          matchExpressions:
            - key: test.myannot
              operator: DoesNotExist
        ...
```

| Поле             | Назначение                                                                                                                                                                                                                            |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| matchExpressions | Значение метки (labels). <br> Передаются поля <br>1. key (Ключ метки (label)) <br>2. operator (Операция при сравнении метки (label). Возможные значения: In / NotIn /  Exists  / DoesNotExists) <br>3. values(Значение метки (label)) |




## matchConditions

Условия на проверку старого/нового состояния конфигурации

```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      match:
        ...
        matchConditions:
          object:
            - path: spec.template.spec.containers[? @.name == `name1`]
              condition: MustExist
          oldObject:
            - path: spec.containers[? @.name == `name2`]
              condition: MustExist
            - path: spec.containers[? @.name == `name3`]
              condition: MustNotExist
        ...
```

| Поле                      | Назначение                                                                            |
|---------------------------|---------------------------------------------------------------------------------------|
| [oldObject](#(old)Object) | Секция для проверки бывшей реализации CRD для принятия решения о проведении валидации |
| [object](#(old)Object)    | Секция для проверки новой реализации CRD для принятия решения о проведении валидации  |

## (old)Object

Секция для проверки бывшей/новой реализации CRD для принятия решения о проведении валидации 

| Поле      | Назначение                                                                                                                                                                                                                                                         |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| path      | Конкретизация секции, формата [JMESPath](https://jmespath.org/) query                                                                                                                                                                                              |
| condition | enum: <br>1. MustExist - ожидаемый результат "true" в рамках обработки секции path (наличие любого текста, либо boolean 'true') <br> 2. MustNotExist - ожидаемый результат "false" в рамках обработки секции path (отсутствие любого текста, либо boolean 'false') |





## rule


```yaml
kind: Scope
apiVersion: kubelatte.io/v1alpha1
metadata:
  name: kubelatte-validation-rule
spec:
  type: validation
  items:
    - name: validation-istio-crd
      ...
      rule:
        simples:
          - name: name-rule
            path: spec.group
            value: *\.istio\.io            
            action: (allow | deny)
            message: Нельзя создавать такое безобразие :)

        или

        rego:
          template: validator_namespace/rego-template-name
          parameters: |-
            crit1:
              - name: myname
                value: value1
            crit2:
              - name: myname
                value: value12  
```

| Поле                | Назначение                             |
|---------------------|----------------------------------------|
| [rego](#rego)       | Указания на валидацию правил типа rego |
| [simples](#simples) | Указания на валидацию обычных правил   |

Тип описания правил "rego" находится в приоритете над типом "simples", поэтому при описании обоих полей будет рассматриваться только те правила, которые описаны в поле "rego". Рекоммендуется использовать один тип правил: либо "rego", либо "simples".



## rego

| Поле       | Назначение                                                                                                                                                       |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| template   | Путь до конфигурации «kind: Template» в namespace, в котором реализованы правила regoRule и к которому будут применены ограничения                               |
| parameters | Параметры, которые необходимо передать в конфигурацию  «kind: Template» для корректной отработки правил regoRule. В этом поле может быть указана любая структура |

Полезные ссылки для работы с rego указаны в разделе [template](template.md#type)

## simples

| Поле    | Назначение                                                                                                                                                                                                         |
|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name    | Наименование правила                                                                                                                                                                                               |
| path    | Путь до рассматриваемого поля                                                                                                                                                                                      |
| value   | Значение поля из "path"                                                                                                                                                                                            |
| action  | Опция установки правила мутации/валидации <br> Возможные зачения: deny, allow. По умолчанию для типа мутации стоит allow, то есть разрешающие правила ; для типа валидации стоит deny, то есть запрещающие правила |
| message | Опция вывода сообщения о причине невозможности мутировать/валидировать ресурс                                                                                                                                      |

